home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / BICSF.ZIP / BICSF-info next >
INI File  |  1993-05-04  |  26KB  |  572 lines
  1. [Slightly edited from a mail I received --Guido]
  2.  
  3. From: Stephen Travis Pope
  4. To: Guido van Rossum
  5. Subject: FAQ: Audio File Formats--The High End
  6.  
  7. Dear Mr. van Rossum,
  8.  
  9. Hoe gaat't? (I worked in Amsterdam for a while and hou van Holland.)
  10.  
  11. INTRODUCTION
  12.  
  13. I recently came across InternetTalkRadio while working at the Swedish
  14. Institute for Computer Science, and read with great interest your
  15. document on audio file formats. I find this a very valuable service to
  16. the community and have one question and one contribution. Maybe I
  17. should make the contribution first.
  18.  
  19. I have been involved in computer music and DSP since the early 1970's,
  20. and have used more sound file formats than I care to remember (well,
  21. actually I can't remember several of them). While your document treats
  22. in detail the requirements of, and formats used in, telecommunications
  23. and personal computer-based musical applications, I think it would
  24. profit from more detail about the high-end formats and sound file
  25. systems used in multi-channel computer music production. I will attempt
  26. to provide you with the information I'm aware of below, with the
  27. assumption that you may edit it according to your needs if you choose
  28. to include or mention it in future editions of your FAQ.
  29.  
  30. HISTORY
  31.  
  32. In your list of "self-describing file formats" you mention the "IRCAM"
  33. sound file system. This software has now been superseded by the
  34. so-called "BICSF" (for Berkeley/IRCAM/CARL Sound File system) software
  35. release. I include the standard document describing BICSF as an
  36. Appendix to this letter. More recently, there has been an effort at
  37. Princeton (Prof. Paul Lansky) and Stanford (myself) to standardize
  38. several extensions to BICSF, which I'll outline below.
  39.  
  40. During the late 1970's and early 1980's, several sites developed
  41. UNIX-based sound file systems for use in computer music. These early
  42. systems generally included real changes to the UNIX file system, so
  43. that separate disks or disk partitions were used for sound storage.
  44. (Many still feel this is a good idea.)
  45.  
  46. The "root" of most of this work is the "csound" file system (first
  47. released around 1980) (not to be confused with the MIT programming
  48. language of the same name--which it predates), developed by D. Gareth
  49. Loy at the Computer Audio Research Lab (CARL) at UC San Diego. It is a
  50. real-time, high-throughput sound file system that ran on DEC VAX and
  51. PDP-11 computers before the advent of the Berkeley file system. Csound
  52. is part of the CARL music software distribution. This package also
  53. includes the cmusic language (a simple C-based Music V descendent
  54. written by F. Richard Moore), and many other tools such as vocoders and
  55. configurable reverberators. The CARL software distribution is still
  56. available for a small license fee, and now runs on Sun, NeXT, SGI, and
  57. various other UNIX hardware. The CARL software is documented profusely
  58. in Dick Moore's book "The Elements of Computer Music" (see references).
  59.  
  60. Robert Gross (then at UCB, now at Sun), based his cylinder-contiguous
  61. sound file system (CCSS) on this. Robert took it with him when he moved
  62. to Paris to work at IRCAM in the early 1980's, and they extended it
  63. there. Some time in the later 1980's the several strains of csound
  64. spin-offs were merged into BICSF, which is still used in computer music
  65. circles and offers several advantages over simpler systems such as the
  66. NeXT/SPARC or even lower forms of sound file life.
  67.  
  68. In an effort to offer interoperability between the BICSF and NeXT/SPARC
  69. systems, Paul Lansky at Princeton (the author of "cmix" tool kit, the
  70. best thing since velcro if you ask me), altered the BICSF header so
  71. that the first 28 bytes "just happen" to be identical to the NeXT/SPARC
  72. header. The "dataLocation" offset is set to 1024 (or a multiple
  73. thereof) to allow a large header. What comes between the "standard"
  74. 28-byte header and the sound may then include the additional
  75. information described below. I have further extended this to allow
  76. more detailed annotation of sound files. I needed this because I
  77. realize computer music compositions that typically involve several
  78. thousand source files amounting to several gigabytes, and required very
  79. flexible and scalable tools. I interface to these formats with both C-
  80. and Smalltalk-language programs (most of which are in the public
  81. domain).  I will refer to this extended BICSF format as "BICSF" below.
  82.  
  83. THE BICSF SOUND FILE SYSTEM
  84.  
  85. Three topics are of interest in the BICSF system: the sound file header
  86. structure, the sound file storage system, and the utilities the system
  87. provides for sound file manipulation. I will discuss each of these
  88. in turn.
  89.  
  90. All but the most Neanderthal sound file formats include some sort of
  91. file header describing the sample rate, sample format, and other
  92. relevant data. The flexibility of this data structure can have a large
  93. influence on the power of the tools that one can build to manipulate
  94. sound files. Modern multimedia and high-quality audio applications
  95. really demand an easily extensible, scalable sound file format.
  96.  
  97. Going beyond the basic fields of a typical sound file header (e.g., the
  98. NeXT/SPARC structure described in Appendix 2 of your FAQ), at least
  99. three types of information should be stored with sound files: (1) an
  100. ASCII text comment describing the sound file's contents; (2) the
  101. maximum amplitude per channel (with the frame index where it appears);
  102. and (3) a collection of named cue points in the sound file. Other
  103. useful information that might be included in the header are the pitch
  104. (scalar or vector), a transcription of the spoken text of a sound, the
  105. envelope (an array of integer or floating-point values), etc.  Further,
  106. processing-method-specific, features such as the names of compression
  107. algorithms, noise gate thresholds, or other file names (for the case of
  108. a "virtual" sound file, described next), are also found.
  109.  
  110. As an example, below is a print out of an extended BICSF sound file
  111. header taken from the Smalltalk-based MODE tool kit (see references).
  112. The lines in this dump correspond to the fields of the C-data structure
  113. or the instance variables of a Smalltalk class description. Note that
  114. strings are enclosed in single-quotes, and that hash-marks (#)
  115. intriduce symbolic names in Smalltalk.
  116.  
  117.  name:      'snd/AllGatesAreOpen/Michi_1/slower_c/4a.snd'
  118.  rate:      44100.0
  119.  channels:  1
  120.  format:    #linear16Bit
  121.  duration:  1.42367 sec
  122.  maxAmp:    Dictionary (#'1'->10700->23345)
  123.  size:      126592 bytes
  124.  modified:  93 Apr 25   5:05:22 pm
  125.  text:      'droem och vaka' 
  126.  comment:   'Transposed down about a minor third and slowed down by 35%'
  127.  cueList:   Dictionary (#droem->(271 to: 29740), 
  128.                   #och->(31815 to: 41035), 
  129.                   #vaka->(41036 to: 62755))
  130.  script:    'pv 44100 1024 8192 128 173 0.82 0 0 -i'
  131.  parent:    'snd/AllGatesAreOpen/Michi_1/src/4a.snd'
  132.  envelope:  (an array of 1024 integers)
  133.  
  134. The maximum amplitude field(s), which are printed above as Smalltalk
  135. dictionaries, store the channel number, the sample frame at which the
  136. value occurred, and the maximum sample's value, i.e., the file above
  137. has one channel whose max. is 23345 at sample frame 10700). The cue
  138. fields have symbolic names, and their values are sample intervals,
  139. i.e., the word "och" ("and" in Swedish) begins at sample frame 31815
  140. and ends at 41035. It is possible to have a sound file that has no
  141. samples of its own, but only cue points into another sound file, a
  142. "virtual sound file." The virtual sound file can include either a file
  143. name and sample range, or a file name and a cue name.
  144.  
  145. [Implementation detail for C hackers] These additional fields can come
  146. in any order and number and have variable lengths, so they are stored
  147. in the header with a key (an integer that is #defined somewhere), a
  148. length, and the data they hold onto.
  149.  
  150. In the csound and CCSS systems, the header also included disk cylinder
  151. pointers, so that it could be stored separately from the sample data,
  152. such as on a normal UNIX file system. More recent implementations have
  153. the header followed immediately by the contiguous sample data, though
  154. this has both advantages and disadvantages. A non-contiguous,
  155. chunk-oriented format might be more flexible. There is still a debate
  156. in the computer music and audio DSP community as to whether this is
  157. necessary or desirable. On the one hand, the Berkeley file system and
  158. its descendents can support partitions with large block sizes, thereby
  159. enabling the high throughput required for real-time performance of
  160. (e.g.,) quadrophonic 16-bit files ar 48 kHz (a frequently-used format).
  161. On the other hand, as mentioned in the BICSF document below, "There are
  162. several reasons to segregate soundfiles from regular UNIX files. [...]
  163. You do not want realtime sound I/O to be in competition with
  164. timesharing I/O. Expect an increase of up to 50% for having a separate
  165. disk and controller for sound."
  166.  
  167. There are several interesting other features of extended-BICSF headers,
  168. but this introduction should serve to heighten readers' awareness of
  169. what is possible, and hopefully motivate the development of such
  170. facilities based on other popular formats such as AIFF.
  171.  
  172. The utilities that are part of BICSF mirror the UNIX file manipulation
  173. shell commands, but generally have "sf" appended to their names. The
  174. user has a "current sound file directory" that is distinct from his or
  175. her UNIX current working directory. In modern versions of BICSF, where
  176. sound files are often stored as regular UNIX files, many of these (such
  177. as "cpsf" or "rmsf"), are not needed. Others, such as "lsf," "fromsnd,"
  178. and "tosnd" (previously called "sndin" and "sndout"), are still
  179. generally needed, and are often given hideous and unnecessarily unclear
  180. names such as "sndinfo." Several utilities exist that accept a variety
  181. of sound file formats, such as the SGI Indigo machine's sound tools
  182. that can process either AIFF or NeXT/SPARC files. (Perhaps we should
  183. build "SOX" into our play programs so we don't have to use it
  184. explicitly.)
  185.  
  186. AVAILABILITY
  187.  
  188. For more information on getting the CARL software distribution, contact
  189. the center's director, F. Richard Moore (frm@ucsd.edu) or Susan Fichera
  190. (sfl@sdcarl.ucsd.edu).
  191.  
  192. Paul Lansky's cmix tools are available via ftp from the directory
  193. pub/music on the server princeton.edu.
  194.  
  195. The MODE Smalltalk tools are available via ftp from the directory
  196. pub/st80 on the server ccrma-ftp.stanford.edu.
  197.  
  198. REFERENCES
  199.  
  200. Anyone performing sound I/O on a time-sharing system (like UNIX) should
  201. be referred to Susan Fichera's excellent discussion of the issues
  202. involved in real-time I/O in these real-time-hostile environments. Her
  203. article is: "Machine Tongues XIII: Real-Time Audio Conversion under a
  204. Time-Sharing Operating System" and appeared in "Computer Music Journal"
  205. 15(3):27-40 (Fall, 1991).
  206.  
  207. F. Richard (Dick) Moore's "The Elements of Computer Music" is highly
  208. recommended as a general introduction to CM and digital audio signal
  209. processing. It teaches his cmusic sound compiler language. It appeared
  210. in 1990 from Prentice-Hall books.
  211.  
  212. My own MODE (Musical Object Development Environment) was described in
  213. detail in the article "The Interim DynaPiano: An Integrated Computer
  214. Tool and Instrument for Composers" in "Computer Music Journal"
  215. 16(3):73-91 (Fall, 1992).
  216.  
  217. A good introduction to software sound synthesis that also addresses
  218. sound file management issues is "Machine Tongues XV: Three Packages for
  219. Software Sound Synthesis" by yours truly in "Computer Music Journal"
  220. 17(2):23-54 (Summer, 1993). This article also introduces and compares
  221. cmusic, csound (the language), and cmix.
  222.  
  223. ====================================================================
  224. ====================================================================
  225.  
  226. Stephen Travis Pope
  227. stp@ccrma.stanford.edu (in Palo Alto), stp@sics.se (in Stockholm)
  228.  
  229. ==============================================================
  230. ==============================================================
  231.  
  232. APPENDIX: BICSF Description 
  233. (written by ? around 1988, included here unedited) (available by ftp
  234. from the file pub/st80/mode/doc/BICSF.t on ccrma-ftp.stanford.edu)
  235.  
  236.  
  237.          BICSF Berkeley/IRCAM/CARL Sound Filesystem
  238.  
  239.                           ABSTRACT
  240.  
  241.           BICSF is a collection of programs which
  242.      implement a filesystem for digital audio applica-
  243.      tions running under Berkeley UNIX.  This document
  244.      gives an overview and describes the installation
  245.      procedure.
  246.  
  247. CREDITS
  248.  
  249. Contributors to this suite of programs are numerous, but the
  250. main outlines of the system are due to the work of
  251. +    Marshall Kirk  McKusick,  William  N.  Joy,  Samuel  J.
  252.      Leffler, Robert S. Fabry for the creation of the Berke-
  253.      ley Fast Filesystem,
  254. +    Gareth Loy at CARL for the prototype CARL csound(1carl)
  255.      filesystem,
  256. +    Rob Gross and Dan Timis at IRCAM for  the  IRCAM  sound
  257.      filesystem,
  258. +    Brad Garton at Columbia  for  the  Digisound-16  device
  259.      driver and associated play and record programs.
  260.  
  261. The soundfile system code here is largely that of Rob  Gross
  262. and  Dan  Timis  of  the IRCAM group.  Author ascription has
  263. been appended to the manual pages where known.
  264.  
  265. The device drivers were written by:
  266. +    DSC-200: Rusty Wright at CARL,
  267. +    Digisound 16: Brad Garton at Columbia Princeton,
  268. +    Dyaxis: Susan Fichera at CARL.
  269.  
  270. THe Digisound 16 driver was updated for SUNOS4.0 by Susan Fichera.
  271. The integration of these various sources  into  one  package
  272. was done by Gareth Loy and Abe Singer at CARL and CMIL.
  273.  
  274. LIST OF PROGRAMS AND ALIASES
  275.  
  276. Following is a list  of  programs  and  aliases,  and  brief
  277. descriptions:
  278.       ALIASES USING STANDARD UNIX COMMANDS
  279.         catsf   - concatenate soundfiles
  280.         chgrpsf - change soundfile group ownership
  281.         chmodsf - change soundfile mode
  282.         chownsf - change soundfile ownership
  283.         cpsf    - copy soundfile
  284.         mkdirsf - make soundfile directory
  285.         mvsf    - move a soundfile
  286.         pwdsf   - print working soundfile directory
  287.         rmdirsf - remove (empty) soundfile directory
  288.         rmsf    - remove soundfile (or directory tree)
  289.  
  290.       BACKWARD COMPATABILITY
  291.         sndin   - read from soundfile
  292.         sndout  - write to soundfile
  293.  
  294.       SPECIAL PROGRAMS
  295.         createsf        - prepare soundfile for recording
  296.         fromsf  - read from soundfile
  297.         gainsf  - normalize or adjust gain of soundfile
  298.         lsf     - list sound files
  299.         normsf  - normalize amplitude of soundfile
  300.         pansf   - pan sound file
  301.         peaksf  - compute peak amplitude and record in soundfile header
  302.         querysf - print out contents of header
  303.         restorsf - restore soundfile from csound dumpsf tape
  304.         retrosf - retrograde a soundfile
  305.         scalesf - gain scale a soundfile
  306.         setsf   - set or modify soundfile header parameters
  307.         sndawk  - signal modification language similar to awk for soundfiles
  308.         swabsf  - swap bytes of samples in soundfile
  309.         tarsf   - tape archive of soundfiles
  310.         tosf    - write to soundfile
  311.         transpsf        - transpose pitch of soundfile
  312.         xdr     - convert soundfile to Sun external data representation
  313.  
  314.       PLAYBACK/RECORD/MONITOR PROGRAMS
  315.         monitor - monitor digital output of ADCs
  316.         play    - play soundfile
  317.         record  - record soundfile
  318.  
  319. NAMES OF PROGRAMS
  320.  
  321. In the interests of name coherency, some programs have  been
  322. renamed  from  their  original  forms  at  CARL,  IRCAM, and
  323. Columbia-Princeton.
  324.       PROGRAMS:
  325.         ORIGINAL            RENAMED
  326.         sfcreate            createsf
  327.         sndcat              catsf
  328.         sndgain             gainsf
  329.         sndin               fromsf
  330.         sndinfo             querysf
  331.         sndnorm             normsf
  332.         sndout              tosf
  333.         sndpan              pansf
  334.         sndpeak             peaksf
  335.         sndreverse          retrosf
  336.         sndscale            scalesf
  337.         sndset              setsf
  338.         sndtransp           transpsf
  339.  
  340.       PLAY, RECORD, ETC:
  341.         DigiSound-16:       ai{play,record,monitor,reset}
  342.         Dyaxis:             dy{play,record}
  343.         DSC-200:            ds{play,record}
  344.  
  345. Aliases have been created for all the  original  names,  and
  346. are   listed   along   with  the  rest  of  the  aliases  in
  347. ./bicsf/std.sfaliases.m4.
  348.  
  349. ORGANIZATION OF SOFTWARE
  350.  
  351. Software is divided into three groups:
  352. +    device drivers, found in subdirectory ../sys,
  353. +    applications programs which depend upon  type  of  con-
  354.      verters,  found  in subdirectories ./{ds,ai,dy}play and
  355.      ./{ds,ai,dy}record,
  356. +    soundfile manipulation and signal  processing  programs
  357.      (found in the rest of the directories).
  358.  
  359. BRIEF THEORY OF OPERATION
  360.  
  361. Using BICSF, one  is  presented  with  two  current  working
  362. directories:  one's  regular  UNIX current working directory
  363. (cwd), plus the BICSF cwd, which is initialized to point  to
  364. one's  home  soundfile directory.  Soundfiles are ordinarily
  365. partitioned on a separate disk from other  files.   However,
  366. the  BICSF  soundfile  directory  is  really a standard UNIX
  367. filesystem at bottom.  Having soundfiles on  separate  disks
  368. from regular UNIX disks avoids competition for head movement
  369. with regular UNIX processes.  It  is  also  advisable  where
  370. possible  to  have  a separate disk controller for soundfile
  371. disks to improve throughput for high sampling rates.
  372.  
  373. There are several reasons to segregate soundfiles from regu-
  374. lar UNIX files.
  375. +    Conventional wisdom is that the block/fragment size  of
  376.      the soundfile partitions should be set to their maximum
  377.      (currently 8K blocks and 8K fragments).  This is desir-
  378.      able  for  maximum  disk  throughput.   The  bigger the
  379.      blocks, the more efficient the disk I/O  can  be.   But
  380.      UNIX files tend to favor smaller granularization, since
  381.      there tend to be more of them,  and  they  tend  to  be
  382.      small.   It  is more common to have UNIX partitions set
  383.      to 4k/512 to allow more effective filling of the  disk.
  384.      Thus, the two types of files demand different treatment
  385.      to optimize space (for UNIX files) and speed (for BICSF
  386.      files).
  387. +    System  administration:  soundfiles  are  BIG.   It  is
  388.      better to have them separate from regular UNIX files so
  389.      you don't have to do huge system dumps of  user's  home
  390.      directory  trees.   In  fact,  at  CARL, we do not dump
  391.      soundfile systems, but leave this to the users to do as
  392.      they see fit.
  393. +    Speed of throughput: you do not want realtime sound I/O
  394.      to  be  in competition with timesharing I/O.  Expect an
  395.      increase of up to 50% for having a  separate  disk  and
  396.      controller for sound.
  397.  
  398. The idea of simultaneous working directories  for  UNIX  and
  399. BICSF  filesystems  overcomes  the problem of having to name
  400. long absolute pathnames to get to  one's  soundfiles.   This
  401. implementation (developed by Robert Gross) consists of a set
  402. of aliases listed in ./bicsf/std.sfaliases.m4.  An  environ-
  403. ment  variable  SFDIR contains the current working soundfile
  404. directory.  The UNIX command has a  BICSF  counterpart  with
  405. the following definition:
  406.         alias     pwdsf     '(cd $SFDIR; /bin/pwd \!*)'
  407.  
  408. Likewise, the UNIX command has this counterpart:
  409.         alias     catsf     '(cd $SFDIR; /cmil/bin/catsf \!*)'
  410.  
  411. cdsf, the BICSF equivalent of sets the SFDIR variable  (it's
  412. definition  repays  careful  study). All BICSF programs must
  413. have such an alias as shown above.
  414.  
  415. ADJUSTING FOR LOCAL CONDITIONS
  416.  
  417. You should  inspect  the  aliases  in  std.sfaliases.m4  and
  418. std.cshrc.m4  to  make  sure  they agree with local require-
  419. ments.  In particular, check the play, record,  and  monitor
  420. aliases  in  std.sfaliases.m4,  and  set them to execute the
  421. play/record programs for the converters you are using.  Also
  422. check values of BINSF, ROOT_SFDIR, HOME_SFDIR, and SFDIR for
  423. local conditions.
  424.  
  425. When the system  is  installed,  these  two  files  are  run
  426. through  the UNIX macro preprocessor to resolve the location
  427. of the programs the aliases refer to.   m4  macros  defining
  428. standard pathnames for executables, manual pages, libraries,
  429. alias files, sources,  etc.  must  be  listed  in  the  file
  430. config.m4,  usually  located in /usr/include/carl/config.m4.
  431. See config.m4(1carl) for details.
  432.  
  433. SOURCES
  434.  
  435. Sources may be placed in one  of  several  places  depending
  436. upon   local   conventions.    At   CARL,   this   path   is
  437. /carl/src/carl/src/bicsf.  Elsewhere, a good place to put it
  438. (or find it) is /`hostname`/src/import/carl/src/bicsf, where
  439. `hostname` is the name of your machine.
  440.  
  441.      The  applications  programs  depend  upon  a   library:
  442. libbicsf.a.   After  creation, this library may be in one of
  443. several places, depending upon local conventions.  At  CARL,
  444. this  path is /carl/lib/libbicsf.a.  Elsewhere, a good place
  445. to put it (or find it) is /`hostname`/lib/libbicsf.a.
  446.  
  447.      It can also be put in /usr/local/lib/libbicsf.a, but as
  448. this  area  is usually wiped out across upgrades of UNIX, it
  449. is preferable to make a  symbolic  link,  /usr/local/lib  ->
  450. /`hostname`/lib.   In  this  way, the loader, can still find
  451. local libraries, allowing the loader's -l flag convention:
  452.      % cc file.c -lbicsf
  453. to succeed.  Otherwise, a full path to  the  file  could  be
  454. given:
  455.      % cc file.c /`hostname`/lib/libbicsf.a
  456.  
  457. Include files in the source code all make generic references
  458. to  include files.  The Makefiles in each directory are made
  459. from their Makefile.m4 prototypes in each source  directory,
  460. and  compile  the  programs to look in the correct locations
  461. for include files.  These are  almost  universally  relative
  462. paths   to   the  directory  ./include  (except  for  device
  463. drivers).
  464.  
  465. HARDWARE INSTALLATION
  466.  
  467. Besides the installation of your converters, it is important
  468. to block out appropriate partitions for BICSF soundfile par-
  469. titions, and give  them  the  proper  block/fragment  sizes.
  470. Conventional  wisdom  is  that you want to set them to 8K/8K
  471. block/fragment size.   The larger the  block/fragment  size,
  472. the  more efficient the disk can be in reading/writing data.
  473. If possible, you do want sound on a separate physical  disk,
  474. not  sharing  any  other  UNIX function, including swapping,
  475. etc.  It's also useful if sound disks are on  separate  con-
  476. trollers.   CARL  benchmarks are that a Digisound-16 can run
  477. 48,000Hz stereo from a Fujitsu Eagle with a single  Xylogics
  478. 450  controller on a Sun-3 with a little spare bandwidth.  A
  479. second controller helps a lot.  There are some files in  the
  480. device  driver  directories  for  the  ai  driver  (for  the
  481. Digisound-16) which  suggest  further  performance  enhance-
  482. ments.
  483.  
  484. DEVICE DRIVER INSTALLATION
  485.  
  486. Refer to the appropriate subdirectory in ../sys for the type
  487. of  converter  you  have  and follow the directions you find
  488. there.
  489.  
  490. SOFTWARE INSTALLATION
  491.  
  492. The code is installed using standard CARL  Software  conven-
  493. tions.   If this code is being installed as part of the CARL
  494. Software  Distribution,  the  process   should   be   mostly
  495. automatic,  save for the installation of the device drivers.
  496. Refer to the instructions for the Distribution, but all that
  497. need be done is to first say
  498.                   make
  499. then              make install
  500. and finally       make clean
  501.  
  502. To install standalone, proceed as follows:
  503.  
  504. First, you need a copy of libcarl.a, from the CARL  software
  505. distribution  to  compile  some  routines,  so  don't bother
  506. unless you have one elsewhere, or are  willing  to  do  wri-
  507. tearounds  (which wouldn't be too difficult) for the missing
  508. routines.
  509.  
  510. Edit the file ./include/config.m4,  which  contains  default
  511. and built-in pathnames for programs.  For standalone instal-
  512. lation, the most important are  m4SNDFILESYSTEM,  m4INCLUDE,
  513. m4DESTDIR, and m4MANDIR.
  514.  
  515. Then execute the file ./Makefirst as follows:
  516.                   % make -f Makefirst
  517.  
  518. This creates the subdirectory  /usr/include/carl,  and  puts
  519. the  file ./include/config.m4 in it.  It is strongly advised
  520. that this subdirectory be used.  If you want to put it some-
  521. where  else,  you  must  edit  all Makefile.m4 files in this
  522. directory tree to point to the new  directory,  plus  change
  523. any    C    program    files    that   make   reference   to
  524. /usr/include/carl.   There  is  a  script  to   change   the
  525. makefiles  called  ./misc/fixmakefiles  that  you can use to
  526. expedite this process, if necessary.
  527. Next, say         % make
  528.  
  529. which does the following steps:
  530. +    remakes all Makefiles with correct paths,
  531. +    installs the  remaining include files in
  532.      /usr/include/carl,
  533. +    builds the library
  534. +    compiles application programs.
  535.  
  536. Next say          % make install
  537.  
  538. which  will  install  binaries,  manual  pages,  and  system
  539. aliases.
  540.  
  541. Lastly, say       % make clean
  542.  
  543. to remove executables and .o files.
  544. To run off documentation, say
  545.  
  546.                   $ make roffall
  547.  
  548. SYSTEM ALIASES
  549.  
  550. The  contents  of  ./bicsf/std.sfaliases  must  somehow   be
  551. sourced  by  all users when they log in.  Furthermore, it is
  552. useful to have users refer to a  master  copy,  so  that  as
  553. BICSF  programs  come  and  go,  a single file only needs be
  554. changed.  At CMIL, for instance, this is done as follows.
  555.  
  556. All users have a standard .cshrc file in their  home  direc-
  557. tories which contains the following line:
  558.         source /`hostname`/lib/std.cshrc
  559. where `hostname` is either the name of the machine, or  some
  560. other  well-known  local  path.   The file std.cshrc in turn
  561. sources  /`hostname`/lib/std.sfaliases,  which   initializes
  562. shell variables and establishes the system aliases for BICSF
  563. commands.
  564.  
  565. There is a prototype .cshrc file, ./bicsf/dotcshrc, which is
  566. provided  for convenience.  These should be the basis of the
  567. .cshrc files all users have.  At CARL, we  have  an  adduser
  568. shell script which installs new users.  Part of it's task is
  569. to copy dotcshrc to ~newuser/.cshrc.
  570.  
  571. ============================ E N D ===========================
  572.